home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / db.man < prev    next >
Encoding:
Text File  |  1989-02-20  |  9.6 KB  |  267 lines
  1.  
  2.  
  3.  
  4. Db                    C Library Procedures                     Db
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Db - manipulate simple database files
  12.  
  13. SSYYNNOOPPSSIISS
  14.      ##iinncclluuddee  <<ddbb..hh>>
  15.  
  16.      int
  17.      DDbb__WWrriitteeEEnnttrryy(_f_i_l_e, _b_u_f_f_e_r, _i_n_d_e_x, _s_i_z_e, _l_o_c_k_H_o_w)
  18.  
  19.      int
  20.      DDbb__RReeaaddEEnnttrryy(_f_i_l_e, _b_u_f_f_e_r, _i_n_d_e_x, _s_i_z_e, _l_o_c_k_H_o_w)
  21.  
  22.      int
  23.      DDbb__OOppeenn(_f_i_l_e, _s_i_z_e, _h_a_n_d_l_e_P_t_r, _w_r_i_t_i_n_g, _l_o_c_k_W_h_e_n, _l_o_c_k_H_o_w, _n_u_m_B_u_f)
  24.  
  25.      int
  26.      DDbb__PPuutt(_h_a_n_d_l_e_P_t_r, _b_u_f_f_e_r, _i_n_d_e_x)
  27.  
  28.      int
  29.      DDbb__GGeett(_h_a_n_d_l_e_P_t_r, _b_u_f_f_e_r, _i_n_d_e_x)
  30.  
  31.      int
  32.      DDbb__CClloossee(_h_a_n_d_l_e_P_t_r)
  33.  
  34.  
  35. AARRGGUUMMEENNTTSS
  36.      char          *_f_i_l_e        (in)      The name of a  database
  37.                                           file  on  which to per-
  38.                                           form operations.
  39.  
  40.      char          *_b_u_f_f_e_r      (in/out)  A pointer to  the  area
  41.                                           from  which or to which
  42.                                           to transfer the record.
  43.  
  44.      int           _i_n_d_e_x        (out)     Which record to  access
  45.                                           in  a  database  opera-
  46.                                           tion.
  47.  
  48.      int           _s_i_z_e         (in)      The size of a record.
  49.  
  50.      Db_LockHow    _l_o_c_k_H_o_w      (in)      Method  to   use   when
  51.                                           locking the database.
  52.  
  53.      Db_Handle     *_h_a_n_d_l_e_P_t_r   (in/out)  A pointer to a  ``data-
  54.                                           base handle''.
  55.  
  56.      int           _w_r_i_t_i_n_g      (in)      If non-zero, the  data-
  57.                                           base  file is opened in
  58.                                           write-only mode, other-
  59.                                           wise in read-only mode.
  60.  
  61.  
  62.  
  63. Sprite v.1.0       Printed:  February 20, 1989                  1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Db                    C Library Procedures                     Db
  71.  
  72.  
  73.  
  74.      Db_LockWhen   _l_o_c_k_W_h_e_n     (in)      Determines when to lock
  75.                                           the  database for long-
  76.                                           term accesses.
  77.  
  78.      int           _n_u_m_B_u_f       (in)      Number  of  records  to
  79.                                           buffer   when   reading
  80.                                           from database.
  81.  
  82. _________________________________________________________________
  83.  
  84. DDEESSCCRRIIPPTTIIOONN
  85.      These functions provide shared access  to  files  containing
  86.      arbitrary  numbers  of  fixed-length records.  There are two
  87.      ways to access the files.  The  simplest  way  to  access  a
  88.      database  file  is to use DDbb__WWrriitteeEEnnttrryy(()) and DDbb__RReeaaddEEnnttrryy(())
  89.      to open the file, access a record, and close the file again.
  90.      An alternative method is to use DDbb__OOppeenn(()) to obtain a hhaannddllee
  91.      for the file, use DDbb__PPuutt(()) or  DDbb__GGeett(())  to  write  or  read
  92.      entries,  respectively, and use Db_Close() to close the file
  93.      when it is no longer needed.  In this case, the _n_u_m_B_u_f argu-
  94.      ment  is  used  to specify how many records to buffer inter-
  95.      nally when doing reads  (it  must  be  specified  as  0  for
  96.      writes).
  97.  
  98.      The Db library provides a simple locking facility  to  allow
  99.      shared  access  to files, built on top of the fflloocckk(()) system
  100.      call.  Database files can be accessed without  using  locks,
  101.      or  using  the  standard  fflloocckk(())  call  in blocking or non-
  102.      blocking mode.  Unfortunately, hosts  can  hold  locks  when
  103.      they crash, so a program that performs a blocking lock could
  104.      wait indefinitely for a lock if no additional  mechanism  is
  105.      used.   The  Db library allows locks to time out, and it can
  106.      optionally break a lock if the lock times out.  The time-out
  107.      period is currently fixed.  The different options are speci-
  108.      fied by the Db_LockHow type:
  109.  
  110.           typedef enum {
  111.               DDBB__LLOOCCKK__NNOO__BBLLOOCCKK,       /* return immediately with error */
  112.               DDBB__LLOOCCKK__PPOOLLLL,           /* poll the lock; time out if necessary */
  113.               DDBB__LLOOCCKK__WWAAIITT,           /* wait indefinitely */
  114.               DDBB__LLOOCCKK__BBRREEAAKK,      /* poll, plus break the lock if needed */
  115.               DDBB__LLOOCCKK__NNOONNEE,           /* do not lock the file at all */
  116.           } Db_LockHow;
  117.  
  118.      The DDbb__WWrriitteeEEnnttrryy(()) and  DDbb__RReeaaddEEnnttrryy(())  procedures  take  a
  119.      Db_LockHow  parameter  to determine how to lock the database
  120.      file the one time it is accessed.  In addition to  a Db_Lock
  121.      parameter, DDbb__OOppeenn(()) takes a Db_LockWhen argument to specify
  122.      when to perform the lock.  Generally, when a file  is  going
  123.      to  be  read or written sequentially, one would like to lock
  124.      it before starting to do I/O and unlock it after  finishing.
  125.      If  a  file  is  going to be accessed repeatedly over a long
  126.      period of time, however, it should be opened once but locked
  127.      only during each access.  These options are DDBB__LLOOCCKK__OOPPEENN and
  128.  
  129.  
  130.  
  131. Sprite v.1.0       Printed:  February 20, 1989                  2
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138. Db                    C Library Procedures                     Db
  139.  
  140.  
  141.  
  142.      DDBB__LLOOCCKK__AACCCCEESSSS, respectively.  If the file is  never  to  be
  143.      locked,  then  the  Db_LockWhen argument may be specified as
  144.      DDBB__LLOOCCKK__NNEEVVEERR or the Db_LockHow argument may be specified as
  145.      DDBB__LLOOCCKK__NNOONNEE.
  146.  
  147.      DDbb__WWrriitteeEEnnttrryy(()) and DDbb__RReeaaddEEnnttrryy(()) provide access to a  sin-
  148.      gle record.  They take the _f_i_l_e_n_a_m_e to access; an _i_n_d_e_x into
  149.      the file, the _s_i_z_e of a record; a pointer to a data  _b_u_f_f_e_r;
  150.      and  the  method  of  locking  the  database,  _l_o_c_k_H_o_w.  All
  151.      records must have the same size.  The index  is  zero-based,
  152.      so _i_n_d_e_x 0 refers to the first record in the file.
  153.  
  154.      DDbb__OOppeenn(()) takes the same _f_i_l_e, _s_i_z_e, and  _l_o_c_k_H_o_w  arguments
  155.      as  DDbb__WWrriitteeEEnnttrryy(())  and  DDbb__RReeaaddEEnnttrryy(()).   It also takes an
  156.      argument, _w_r_i_t_i_n_g, which indicates whether  access  will  be
  157.      writing  (1)  or  reading (0); and another argument, _n_u_m_B_u_f,
  158.      which specifies how many records to read from  the  file  at
  159.      once  when  doing reads.  The _l_o_c_k_W_h_e_n argument is described
  160.      above; it indicates whether locking should be done for  each
  161.      access or at the time the file is opened.  DDbb__OOppeenn(()) returns
  162.      a database handle in *_h_a_n_d_l_e_P_t_r.  The storage for the handle
  163.      must  be allocated by the caller of DDbb__OOppeenn(()).  A pointer to
  164.      the  handle  must  be  used  in  later  calls  to  DDbb__PPuutt(()),
  165.      DDbb__GGeett(()), or DDbb__CClloossee(()).
  166.  
  167.      DDbb__PPuutt(()) and DDbb__GGeett(()) are analogous to  DDbb__WWrriitteeEEnnttrryy(())  and
  168.      DDbb__RReeaaddEEnnttrryy(()).   They  are  used in cases when the database
  169.      file is opened by DDbb__OOppeenn(()), for use over an extended period
  170.      of  time.  The _h_a_n_d_l_e_P_t_r  argument must be a handle returned
  171.      by DDbb__OOppeenn(()). The _b_u_f_f_e_r  must be a pointer to  an  area  of
  172.      the  size specified in the call to DDbb__OOppeenn(()).  The _i_n_d_e_x  is
  173.      an integer: if non-negative, it specifies a  record  number,
  174.      like  in  calls  to  DDbb__WWrriitteeEEnnttrryy(()) and DDbb__RReeaaddEEnnttrryy(()).  If
  175.      _i_n_d_e_x  is -1, it specifies that the access should be sequen-
  176.      tial:  the  record  to  be  operated  upon should be the one
  177.      immediately following the last record read or  written.   If
  178.      DDbb__PPuutt(())  or  DDbb__GGeett(())  is called for the first time with an
  179.      _i_n_d_e_x  of -1, the first record is written or read.
  180.  
  181.      DDbb__CClloossee(()) closes a file that  was  opened  with  DDbb__OOppeenn(()).
  182.      _H_a_n_d_l_e_P_t_r  must  point  to  a handle that was initialized by
  183.      DDbb__OOppeenn(()).
  184.  
  185. DDIIAAGGNNOOSSTTIICCSS
  186.      All routines return 0 if they complete  successfully.   Upon
  187.      error, they return -1 and the _e_r_r_n_o variable  contains addi-
  188.      tional information about what error occurred.
  189.  
  190. KKEEYYWWOORRDDSS
  191.      database, data base, lock, record, handle
  192.  
  193.  
  194.  
  195.  
  196.  
  197. Sprite v.1.0       Printed:  February 20, 1989                  3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204. Db                    C Library Procedures                     Db
  205.  
  206.  
  207.  
  208. SSEEEE AALLSSOO
  209.      mig, ulog, flock, dbm
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263. Sprite v.1.0       Printed:  February 20, 1989                  4
  264.  
  265.  
  266.  
  267.